%****************************************************************************%
%* DIET tutorial                                                            *%
%*                                                                          *%
%*  Author(s):                                                              *%
%*    - Ludovic BERTSCH (Ludovic.Bertsch@ens-lyon.fr)                       *%
%*    - Eddy CARON (Eddy.Caron@ens-lyon.fr)                                 *%
%*    - Philippe COMBES (Philippe.Combes@ens-lyon.fr)                       *%
%*                                                                          *%
%* $LICENSE$                                                                *%
%****************************************************************************%
%* $Id: Tutorial.tex,v 1.4 2005/08/22 08:09:17 ycaniou Exp $
%* $Log: Tutorial.tex,v $
%* Revision 1.4  2005/08/22 08:09:17  ycaniou
%* Added the references that are cited in the Tutorial, thus
%* Added the Tutorial.bib file containing the references and
%* Modified the Makefile.am so that a bibtex command is run when the
%*   tutorial is compiled.
%*
%* Revision 1.3  2004/01/05 13:08:27  ecaron
%* Minor typography correction
%*
%* Revision 1.2  2003/12/20 20:43:15  ecaron
%* Update Tutorial for DIET Release 1.0
%*
%* Revision 1.4  2003/12/14 08:01:15  ecaron
%* New version of tutorial (from current to 1.0) (c source file is updating)
%*
%* Revision 1.3  2003/06/16 17:42:03  pcombes
%* Fix header.
%*
%* Revision 1.1.1.1  2003/01/24 16:28:28  pcombes
%* DIET tutorial based on users's day examples
%****************************************************************************%
\documentclass[11pt,a4paper]{article}

\makeatletter
\def\input@path{{../utils}{../../../../publis/utils/styles/}}
\makeatother
\usepackage{fancyheadings}
\usepackage[french]{babel}
\usepackage[latin1]{inputenc}
\usepackage{palatino}
\usepackage{multicol}
\usepackage{verbatim}
%\usepackage{fullpage}
\usepackage[headings]{fullpage}
\usepackage{url}

\usepackage{graphicx}

\newsavebox{\logobox}
\sbox{\logobox}{\includegraphics[scale=0.3]{../UsersManual/fig/logo_DIET.ps}}
\newcommand{\logo}{\usebox{\logobox}}

\renewcommand{\title}{DIET Tutorial}

\pagestyle{fancyplain}
\lhead[\fancyplain{\title}{\title}]
      {\fancyplain{\title}{\title}}
\chead{}
\rhead[\fancyplain{\logo}{\logo}]{\fancyplain{\logo}{\logo}}

\lfoot[\fancyplain{INRIA}{INRIA}]{\fancyplain{INRIA}{INRIA}}
\cfoot[\fancyplain{}{}]{\fancyplain{}{}}
\rfoot[\fancyplain{Page~\thepage}{Page~\thepage}]
      {\fancyplain{Page~\thepage}{Page~\thepage}}


\begin{document}

%%%%
% First sheet
%%%%

\thispagestyle{empty}
\vspace*{3cm}
\vspace*{3cm}

\begin{center}
\includegraphics[scale=.5]{../UsersManual/fig/logo_DIET.ps}\\[2ex]
\textbf{\Huge TUTORIAL\\[2ex]}
\end{center}

\vfill


\noindent
\small{
\begin{tabular}{ll}
  \textbf{VERSION}  & 1.0\\
  \textbf{DATE}     & December 2003\\
  \textbf{PROJECT MANAGER}  & Fr\'ed\'eric \textsc{Desprez}.\\
  \textbf{EDITORIAL STAFF}  & Eddy \textsc{Caron} and Philippe ~\textsc{Combes}.\\
  \textbf{AUTHORS STAFF}    & 
\begin{minipage}[t]{12cm}
  Ludovic \textsc{Bertsh}, Eddy \textsc{Caron}, Philippe ~\textsc{Combes} and Christophe \textsc{Pera}.
\end{minipage} \\
  \textbf{Copyright}& INRIA
\end{tabular}\\
}

\newpage
%\thispagestyle{empty}

%%%%
% End of first sheet
%%%%


\begin{center}
{\Huge DIET Tutorial \par}
\end{center}

\section{Introduction}

This is a tutorial for DIET (Distributive Interactive Engineering
Toolbox). It comes with three directories: \texttt{exercise2},
\texttt{exercise3} and \texttt{solutions}. The exercice directories
contain the skeletons for the programs you will have to write,
\texttt{solutions} contains the programs you should write.

To compile the programs, you will need to have omniORB 3 or 4
installed~\cite{UMOmniORB}. Some tips about omniORB installation
are given in the DIET User's Manual~\cite{UMDIET}, which will be often
refered to in this tutorial.  However, if you still have problems to
install omniORB 4, please contact your system administrator.  In this
document, we will refer to the directory were omniORB has been
installed with the environment variable \texttt{\$\{OMNIORB\_HOME\}}.

\section{Exercise 1: Installing and compiling DIET}

The installation process is described in the User's Manual. Install
DIET in the directory of your choice, for instance
\texttt{\$\{HOME\}/DIET}. For this tutorial, FAST will not be used,
and as regards omniORB, please add the
\texttt{\$\{OMNIORB\_HOME\}/bin} directory in your \texttt{PATH}, or
give the following option to the \texttt{configure} script : \texttt{--with-omniORB=\$\{OMNIORB\_HOME\}}

Compile {\bf and} install DIET. Refer to the User's Manual for more
information.

\section{Exercise 2: An example of matrix computation}

With this example we learn how to program a simple client/server
application that uses DIET. We will use the context of matrix
computation to make this program look more real. We will implement a
basic scalar by matrix product. Then, we will test this program in
different schemes of execution.
\par

\subsection{Files skeletons}

The exercise2 directory, located in your home directory contains all
the skeleton files needed for a quick start. Useful pieces of software
are also included in them. This directory contains the following
files:

\begin{description}
\item[Makefile]{management of dependencies between source and compiled files}
\item[server.c]{program implementing the service (scalar by matrix product)}
\item[client\_smprod.c]{program using the service defined in server.c: the
    matrix is stored in memory}
\item[client\_smprod\_file.c]{same program than client\_smprod\.c, except that
    the matrix is passed as a file to the server}
\end{description}

\subsection{Server-side implementation}

Using the skeleton of program \texttt{server.c}, write a service of scalar by
matrix product. This service will have the following parameters:

\begin{center}
\begin{tabular}{|l|l|}
\hline
parameter & type \\
\hline
a scalar & double \\
a matrix to be multiplied & double \\
the time needed for the product to compute & float \\
\hline
\end{tabular}
\end{center}

The intial matrix is overwritten by the result. The matrix will be
stored in memory. \par

To start, try to define a detailed interface for the service, i.e. a precise
definition of the service \emph{profile}. To do so, look for {\bf in},
{\bf inout} and {\bf out} parameters. \par

Next, program the solve function \texttt{solve\_smprod}, and also the
initialization of the service in the \texttt{main} function. \par

\footnotesize
\begin{verbatim}
int solve_smprod(...) {

}
\end{verbatim}
\normalsize
\noindent
The following function is given to help you:
\footnotesize
\begin{verbatim}
int scal_mat_prod(double alpha, double *M, int nb_rows, int nb_cols, float *time)
\end{verbatim}
\normalsize
\noindent

It mutliplies the scalar \texttt{alpha} by the matrix \texttt{M} a
\texttt{nb\_rows} by \texttt{nb\_cols} matrix. The result are the
matrix \texttt{alpha} $\times$ \texttt{M} and the time of this
operation in seconds.

\subsection{Client-side implementation}

Using the \texttt{client\_smprod.c} skeleton file, write a client for
the service defined above. You will need to initialize a matrix and a
scalar with known values. That way, you will be able to verify if the
answer is correct or not. \par

You will have to remember that the profile used in the client must match 
exactly the server profile.

\subsection{Setting up and testing the client/server}

The file \texttt{env\_vars.bash.in} for bash shell (respectively
\texttt{env\_vars.csh.in} for tcsh shell) contains all the environment
variables needed for the execution of the programs. Verify the values
of those variables, then load this file using the following method:

\footnotesize
\begin{verbatim}
~/> source env_vars.bash   
\end{verbatim}
\normalsize

When done with this operation, you need to start the name server of omniORB:
omniNames. To do that, you must give a port number with the \texttt{-start}
option, on which the service will be opened (and on which the server
``listens''):
\footnotesize
\begin{verbatim}
$ omniNames -start 

Tue Dec 11 14:10:28 2003:

Starting omniNames for the first time.
Wrote initial log file.
Read log file successfully.
Root context is
IOR:010000002b00000049444c3a6f6d672e6f72672f436f734e616d696e672f4e616d696e674
36f6e746578744578743a312e300000010000000000000060000000010102000d000000313430
2e37372e31332e36310000554f0b0000004e616d6553657276696365000200000000000000080
000000100000000545441010000001c0000000100000001000100010000000100010509010100
0100000009010100
Checkpointing Phase 1: Prepare.
Checkpointing Phase 2: Commit.
Checkpointing completed.
$
\end{verbatim}
\normalsize

Then, you have to copy this port number in the omniORB configuration file: the
name and location of this file is given by the environment variable 
\texttt{OMNIORB\_CONFIG} which is defined in the \texttt{env\_vars.bash} file.
\par

Using DIET User's Manual, prepare configuration files (suggestion:
place them in a \texttt{cfgs} directory). You will want to create a
hierarchy of agents, to make it interesting. This hierarchy will
contain at least one MA and one LA.
\par

Compile server and client with the \texttt{Makefile}, then, launch the server
and the client. \par

Finally, launch several servers in different windows (you can use same
or different distributed computers). With different windows, you will
see which one is activated. You should experiment with different
hierarchies.

\subsection{Another version of the service}

In this part, you will modify the server to make it support a slightly
different version of the scalar by matrix product. The matrix will be
transmitted as a file, and not anymore in memory. \par

DIET doesn't impose anything about the data format of files, but it
would be a good idea to facilitate your work to use the data format
used in the skeleton files. This format is just simple text~: the file
contains a serie of numbers, separated by 'space' characters. The
meaning of the numbers is as follows~:

\begin{itemize}
\item{matrix dimensions (number of rows, number of columns)}
\item{matrix values}
\end{itemize}

\par
Create a file containing a matrix, then implement a new service
``\texttt{smprod\_file}'' with the following parameters:

\begin{center}
\begin{tabular}{|l|l|}
\hline
parameter & type \\
\hline
a scalar & double \\
a file containing matrix to be multiplied & double \\
the time needed for the product to compute & float \\
\hline
\end{tabular}
\end{center}

The file is overwritten by the result.

\subsection{Another yet service: The BLAS dgemm}

To compile programs of this exercise, the BLAS library (Basic Linear
Algebric Subroutines) is required.

DGEMM  -  perform  one of the matrix-matrix operations   C :=
       alpha*op( A )*op( B ) + beta*C

The \texttt{dgemm\_} function is part of the BLAS.  It performs the
following matrix-matrix computation:

$$ C := \alpha A B + \beta C $$

$\alpha$ and $\beta$ are scalars, and $A$, $B$ and $C$ are matrices,
with op( A ) an m by k matrix, op( B ) a k by n matrix and C an m by n
matrix

This exercise aims at adding a new service in a DIET platform, that
performs the \texttt{dgemm\_} computation. The idea is to interface
the existing \texttt{dgemm\_} function to a DIET SeD. Here is its
prototype:

\begin{verbatim}
void dgemm_(char   *tA,
            char   *tB,
            int    *m,
            int    *n,
            int    *k,
            double *alpha,
            double *A,
            int    *lda,
            double *B,
            int    *ldb,
            double *beta,
            double *C,
            int    *ldc);
\end{verbatim}

All parameters are given by address. Parameters \texttt{alpha}, \texttt{beta},
\texttt{m}, \texttt{n}, \texttt{k}, \texttt{A}, \texttt{B} and \texttt{C}
correspond exactly to their respective roles in the computation. \texttt{lda},
\texttt{ldb} and \texttt{ldc} are the \emph{leading dimensions} of the
corresponding matrices. Since matrices are stored in a classical one-dimension
array, it is important to specify if they are stored by rows or by columns.
\texttt{*tA} and \texttt{*tB} are characters which have the following semantics:
\begin{center}
\begin{tabular}{|c|c|l|}\hline
tA  &  \multicolumn{2}{c|}{Storage order of A ($m$,$k$)}\\\hline
'T' &  row-major    & [row 1, row 2, ... , row $m$]\\
'N' &  column-major & [col 1, col 2, ... , col $k$] \\\hline
\end{tabular}
\end{center}

For this exercise, there is no need to explore all possibilities
offered by the storage order or the leading dimension. Just set
\texttt{*tA} and \texttt{*tB} to 'N', and \texttt{lda}, \texttt{ldb}
and \texttt{ldc} to the number of rows of the corresponding matrix.

Once you have specified the \emph{profile} of the service, program a
server that implements this service, and a test client, using the file
skeletons in the \textbf{exercise3} directory. Matrices will be stored
in memory.  Eventually, test the client/server architecture, through
DIET, in different contexts of execution.

\bibliographystyle{plain}
\bibliography{Tutorial}

\end{document}
